/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License"),
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup TeeTrusted
 * @{
 *
 * @brief TEE（Trusted Excution Environment）可信执行环境API。
 *
 * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。
 *
 * @since 20
 */

/**
 * @file tee_client_type.h
 *
 * @brief 定义基本数据类型和数据结构。
 *
 * @library libteec.so
 * @kit TEEKit
 * @include <TEEKit/tee_client_type.h>
 * @syscap SystemCapability.Tee.TeeClient
 * @since 20
 */

#ifndef TEE_CLIENT_TYPE_H
#define TEE_CLIENT_TYPE_H

#include <semaphore.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include "tee_client_constants.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定义链表节点类型。
 *
 * @since 20
 */
struct ListNode {
    /** 指向链表中下一个节点的指针。 */
    struct ListNode *next;
    /** 指向链表中上一个节点的指针。 */
    struct ListNode *prev;
};

/**
 * @brief 定义返回值类型。
 *
 * @since 20
 */
typedef enum TEEC_ReturnCode TEEC_Result;

/**
 * @brief 定义通用唯一标识符 (UUID)，符合RFC4122[2]标准。UUID用于标识可信应用 (TA)。
 *
 * @since 20
 */
typedef struct {
    /** UUID的低32位时间字段。 */
    uint32_t timeLow;
    /** UUID的中16位时间字段。 */
    uint16_t timeMid;
    /** UUID的高16位时间字段和版本号。 */
    uint16_t timeHiAndVersion;
    /** 时钟序列和节点值，长度为8字节。 */
    uint8_t clockSeqAndNode[8];
} TEEC_UUID;

/**
 * @brief 定义上下文，表示CA与TEE之间的逻辑连接。
 *
 * @since 20
 */
typedef struct {
    /** TA的文件描述符。 */
    int32_t fd;
    /** 可信应用（TA）的路径。 */
    uint8_t *ta_path;
    /** 与该上下文关联的会话链表。 */
    struct ListNode session_list;
    /** 与该上下文关联的共享内存链表。 */
    struct ListNode shrd_mem_list;
    /**
     * @brief 用于表示共享缓冲区或实现相关数据的联合体。
     *
     * @since 20
     */
    union {
        /**
         * @brief 用于数据交换和同步的共享缓冲区。
         *
         * @since 20
         */
        struct {
            /** 指向共享缓冲区的指针。 */
            void *buffer;
            /** 用于共享缓冲区同步的信号量。 */
            sem_t buffer_barrier;
        } share_buffer;
        /** 实现相关的数据。 */
        uint64_t imp;
    };
} TEEC_Context;

/**
 * @brief 定义CA与TA之间的会话。
 *
 * @since 20
 */
typedef struct {
    /** 会话ID。 */
    uint32_t session_id;
    /** 表示该会话关联服务的UUID。 */
    TEEC_UUID service_id;
    /** 与该会话关联的操作次数。 */
    uint32_t ops_cnt;
    /**
     * @brief 表示会话链表头或实现相关数据的联合体。
     *
     * @since 20
     */
    union {
        /** 会话相关数据的链表头。 */
        struct ListNode head;
        /** 实现相关数据。 */
        uint64_t imp;
    };
    /** 指向与该会话关联的TEEC上下文的指针。 */
    TEEC_Context *context;
} TEEC_Session;

/**
 * @brief 定义一个共享内存块，可用于注册或分配。
 *
 * @since 20
 */
typedef struct {
    /** 指向共享内存缓冲区的指针。 */
    void *buffer;
    /** 共享内存缓冲区的大小。 */
    uint32_t size;
    /** 与共享内存相关的标志位。 */
    uint32_t flags;
    /** 与该共享内存关联的操作次数。 */
    uint32_t ops_cnt;
    /** 指示该内存是否已被分配。 */
    bool is_allocated;
    /**
     * @brief 表示共享内存链表头或实现相关数据的联合体。
     *
     * @since 20
     */
    union {
        /** 共享内存相关数据的链表头。 */
        struct ListNode head;
        /** 实现相关的数据。 */
        void* imp;
    };
    /** 指向与该共享内存关联的TEEC上下文的指针。 */
    TEEC_Context *context;
} TEEC_SharedMemory;

/**
 * @brief 定义指向临时缓冲区的指针。
 *
 * @since 20
 */
typedef struct {
    /** 指向临时缓冲区的指针。 */
    void *buffer;
    /** 临时缓冲区的大小（以字节为单位）。 */
    uint32_t size;
} TEEC_TempMemoryReference;

/**
 * @brief 定义指向已注册或已分配共享内存的指针。
 *
 * @since 20
 */
typedef struct {
    /** 指向已注册或已分配共享内存的指针。 */
    TEEC_SharedMemory *parent;
    /** 共享内存大小。 */
    uint32_t size;
    /** 共享内存偏移量。 */
    uint32_t offset;
} TEEC_RegisteredMemoryReference;

/**
 * @brief 描述一个以值传递的小型原始数据参数。
 *
 * @since 20
 */
typedef struct {
    /** 参数值a。 */
    uint32_t a;
    /** 参数值b。 */
    uint32_t b;
} TEEC_Value;

/**
 * @brief 描述 ION 内存的大小和句柄。
 *
 * @since 20
 */
typedef struct {
    /** ION内存的共享文件描述符。 */
    int ionShareFd;
    /** ION内存的大小。 */
    uint32_t ionSize;
} TEEC_IonReference;

/**
 * @brief 定义TEEC_Operation的参数。
 *
 * @since 20
 */
typedef union {
    /** 临时内存引用。 */
    TEEC_TempMemoryReference tmpref;
    /** 已注册的内存引用。 */
    TEEC_RegisteredMemoryReference memref;
    /** 以值传递的小型原始数据。 */
    TEEC_Value value;
    /** ION内存引用。 */
    TEEC_IonReference ionref;
} TEEC_Parameter;

/**
 * @brief 定义可信用户界面（TUI）的参数。
 *
 * @since 20
 */
typedef struct {
    /** TUI事件类型。 */
    uint32_t event_type;
    /** 返回值，如果事件为getKeycode，则表示按键码。 */
    uint32_t value;
    /** 屏幕刘海区域的大小。 */
    uint32_t notch;
    /** 折叠屏的宽度。 */
    uint32_t width;
    /** 折叠屏的高度。 */
    uint32_t height;
    /** 折叠屏的状态。 */
    uint32_t fold_state;
    /** 折叠屏的某种显示状态。 */
    uint32_t display_state;
    /** 移动设备的物理宽度。 */
    uint32_t phy_width;
    /** 移动设备的物理高度。 */
    uint32_t phy_height;
} TEEC_TUI_Parameter;

/**
 * @brief 定义用于打开会话或发送命令的参数。
 *
 * @since 20
 */
typedef struct {
    /** 值为0表示取消命令，其他值表示执行命令。 */
    uint32_t started;
    /** 使用TEEC_PARAM_TYPES创建的参数类型。 */
    uint32_t paramTypes;
    /** 参数数组，包含最多TEEC_PARAM_NUM个参数。 */
    TEEC_Parameter params[TEEC_PARAM_NUM];
    /** 指向当前操作所属的会话。 */
    TEEC_Session *session;
    /** 取消标志，指示是否取消该操作。 */
    bool cancel_flag;
} TEEC_Operation;

#ifdef __cplusplus
}
#endif

#endif
/** @} */